#ifndef __PLATFORM_LIB_pf_cache_H__
#define __PLATFORM_LIB_pf_cache_H__
#ifdef __cplusplus
extern "C"
{
#endif

#include "pf_common.h"

/******************************************************************************************************/

/*********************************************************************************************
Function Name:  pf_cache_constructor_f
Description  :  Function handler.
                Constructor used to initialize allocated objects.
Inputs       :  void* obj                           : Pointer to the object to initialized.
                void* notused1                      : This parameter is currently not used.
                void* notused2                      : This parameter is currently not used.
Outputs      :  return value                        : 0. you should return 0, but currently 
                                                         this is not checked.
ErrorCodes   :  no
History      :
---------------------------------------------------------------------------------------------
Author                 Date                         Comments
lijz                   2011-6-24                    create
**********************************************************************************************/
typedef int pf_cache_constructor_f(void* obj, void* notused1, int notused2);

/*********************************************************************************************
Function Name:  pf_cache_destructor_f
Description  :  Function handler.
                Destructor used to clean up allocated objects before they are
                returned to the operating system.
Inputs       :  void* obj                           : Pointer to the object to initialized.
                void* notused                       : This parameter is currently not used.
Outputs      :  return value                        : 0. you should return 0, but currently 
                                                         this is not checked.
ErrorCodes   :  no
History      :
---------------------------------------------------------------------------------------------
Author                 Date                         Comments
lijz                   2011-6-24                    create
**********************************************************************************************/
typedef void pf_cache_destructor_f(void* obj, void* notused);

/*
   Definition of the structure to keep track of the internal details of
   the cache allocator. Touching any of these variables results in
   undefined behavior.
 */
typedef struct pf_cache pf_cache_t;

/*********************************************************************************************
Function Name:  pf_cache_create
Description  :  Cache constructor to create an object cache.
                The object cache will let you allocate objects of the same size. It is fully
                MT safe, so you may allocate objects from multiple threads without having to
                do any syncrhonization in the application code.
Inputs       :  const char* name                    : Cache name. This name maybe used for 
                                                      debug purposes.
                size_t bufsize                      : The size of each object in the cache.
                size_t align                        : Alignment size. (Reserved)
                pf_cache_constructor_f* constructor : The function to be called to initialize 
                                                      memory when we need to allocate more 
                                                      memory from the os.
                pf_cache_destructor_f* destructor   : The function to be called before 
                                                      we release the memory back to the os.
                int initial_size                    : Initial amount of cache's object
                int max_free                        : Maximum amount of free cache's object.
Outputs      :  return value                        : Cache pointer.
                                                      Caller must call pf_cache_destroy() to destroy it.
                                                    : NULL. Cache create fail.
ErrorCodes   :  no
History      :
---------------------------------------------------------------------------------------------
Author                 Date                         Comments
lijz                   2011-6-24                    create
**********************************************************************************************/
extern pf_cache_t* pf_cache_create(const char* name, 
                                   size_t bufsize, 
                                   size_t align,
                                   pf_cache_constructor_f* constructor,
                                   pf_cache_destructor_f* destructor,
                                   int initial_size,
                                   int max_free);

/*********************************************************************************************
Function Name:  pf_cache_destroy
Description  :  Cache destructor to destroy an object cache.
                Destroy and invalidate an object cache. You should return all buffers allocated
                with pf_cache_alloc by using pf_cache_free before calling this function. 
                Not doing so results in undefined behavior (the buffers may or 
                may not be invalidated)
Inputs       :  pf_cache_t* cache : Cache pointer to destroy.
Outputs      :  no
ErrorCodes   :  no
History      :
---------------------------------------------------------------------------------------------
Author                 Date                         Comments
lijz                   2011-6-24                    create
**********************************************************************************************/
extern void pf_cache_destroy(pf_cache_t* handle);

/*********************************************************************************************
Function Name:  pf_cache_alloc
Description  :  Allocate an object from the cache.
Inputs       :  pf_cache_t* cache    : Cache pointer. Must be NOT NULL.
Outputs      :  return value         : Object pointer to an initialized object from the cache.
                                       NULL. The allocation cannot be satisfied.
ErrorCodes   :  no.
History      :
---------------------------------------------------------------------------------------------
Author                 Date                         Comments
lijz                   2011-6-24                    create
**********************************************************************************************/
extern void* pf_cache_alloc(pf_cache_t* handle);

/*********************************************************************************************
Function Name:  pf_cache_free
Description  :  Return an object back to the cache.
                The caller should return the object in an initialized state so that
                the object may be returned in an expected state from pf_cache_alloc().
Inputs       :  pf_cache_t* cache    : Cache pointer to the object cache to return 
                                       the object to. Must be NOT NULL.
                void* ptr            : Object pointer to return. Must be NOT NULL.
Outputs      :  no.
ErrorCodes   :  no.
History      :
---------------------------------------------------------------------------------------------
Author                 Date                         Comments
lijz                   2011-6-24                    create
**********************************************************************************************/
extern void pf_cache_free(pf_cache_t* cache, void* ptr);

/******************************************************************************************************/

#ifdef __cplusplus
}
#endif
#endif /* #ifndef __PLATFORM_LIB_pf_cache_H__ */
